gh-144835: Added missing explanations for some parameters in glob and iglob. by facundobatista · Pull Request #144836 · python/cpython

facundobatista · 2026-02-15T14:56:14Z

I took the explanations for the missing parameters from the documentation itself (slightly edited for brevity) for the cases of root_dir and dir_fd in both glob and iglob.

For the case of iglob's include_hidden, I just copied it from glob.

Issue: The glob.glob and glob.iglob docstrings are missing explanation of some parameters #144835

hugovk · 2026-02-15T16:33:34Z

+    If root_dir is not None, it should be a path-like object specifying the
+    root directory for searching. It has the same effect as changing the
+    current directory before calling it. If pathname is relative, the
+    result will contain paths relative to root_dir.
+
+    If dir_fd is not None, it should be a file descriptor referring to a
+    directory, and paths will then be relative to that directory.


Suggested change

If root_dir is not None, it should be a path-like object specifying the

root directory for searching. It has the same effect as changing the

current directory before calling it. If pathname is relative, the

result will contain paths relative to root_dir.

If dir_fd is not None, it should be a file descriptor referring to a

directory, and paths will then be relative to that directory.

If `root_dir` is not None, it should be a path-like object specifying the

root directory for searching. It has the same effect as changing the

current directory before calling it. If `pathname` is relative, the

result will contain paths relative to root_dir.

If `dir_fd` is not None, it should be a file descriptor referring to a

directory, and paths will then be relative to that directory.

I'm wary of "It has the same effect as changing the current directory before calling it" phrasing as we don't want anyone to think that the process wide global cwd is changed by these API calls. I think it may be better to state what the default behavior is when not specified or None. ie "if not specified or None, the search will be conducted from the processes current working directory and returned paths will be relative to that" (Q: is that accurate?)

terryjreedy

I agree with Hugo's suggestions, and yes, backport.

bedevere-app · 2026-02-15T19:45:49Z

When you're done making the requested changes, leave the comment: I have made the requested changes; please review again.

facundobatista · 2026-02-18T14:20:42Z

@hugovk @terryjreedy I have made the requested changes; please review again, thanks!!

bedevere-app · 2026-02-18T14:20:49Z

Thanks for making the requested changes!

@terryjreedy: please review the changes made to this pull request.

facundobatista · 2026-02-18T14:24:05Z

I'm wary of "It has the same effect as changing the current directory before calling it" phrasing as we don't want anyone to think that the process wide global cwd is changed by these API calls. I think it may be better to state what the default behavior is when not specified or None. ie "if not specified or None, the search will be conducted from the processes current working directory and returned paths will be relative to that" (Q: is that accurate?)

@gpshead I understand your concern. I'm using the same wording that in the glob documentation.

Maybe we can improve both? I prefer the "positive description" (indicate what it does, not what it doesn't). What about the following clarification?

    If `root_dir` is not None, it should be a path-like object specifying 
    the root directory for searching. It has the same effect as changing 
    the current directory before calling it (without actually 
    changing it). If pathname is relative, the result will contain 
    paths relative to `root_dir`.

Thanks!

facundobatista · 2026-03-01T21:10:08Z

@hugovk @terryjreedy @gpshead hey! let me know please if you need something else is needed before I go forward with merging this. Thanks!

facundobatista · 2026-03-02T11:56:13Z

@gpshead thanks!

miss-islington-app · 2026-03-02T11:56:31Z

Thanks @facundobatista for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

…ob and iglob. (pythonGH-144836) * Added missing explanations for some parameters in glob and iglob. * News entry. * Added proper 'func' indication in News file. * Consistent use of backticks. * Improved wording. * consistent wording between the two docstrings --------- (cherry picked from commit e542255) Co-authored-by: Facundo Batista <facundo@taniquetil.com.ar> Co-authored-by: Gregory P. Smith <68491+gpshead@users.noreply.github.com>

bedevere-app · 2026-03-02T11:56:42Z

GH-145415 is a backport of this pull request to the 3.14 branch.

bedevere-app · 2026-03-02T11:56:47Z

GH-145416 is a backport of this pull request to the 3.13 branch.

…lob and iglob. (GH-144836) (#145415) Co-authored-by: Facundo Batista <facundo@taniquetil.com.ar> Co-authored-by: Gregory P. Smith <68491+gpshead@users.noreply.github.com>

…lob and iglob. (GH-144836) (#145416) Co-authored-by: Facundo Batista <facundo@taniquetil.com.ar> Co-authored-by: Gregory P. Smith <68491+gpshead@users.noreply.github.com>

…ob and iglob. (python#144836) * Added missing explanations for some parameters in glob and iglob. * News entry. * Added proper 'func' indication in News file. * Consistent use of backticks. * Improved wording. * consistent wording between the two docstrings --------- Co-authored-by: Gregory P. Smith <68491+gpshead@users.noreply.github.com>

Added missing explanations for some parameters in glob and iglob.

abb4ca7

bedevere-app Bot added the awaiting core review label Feb 15, 2026

bedevere-app Bot mentioned this pull request Feb 15, 2026

The glob.glob and glob.iglob docstrings are missing explanation of some parameters #144835

Closed

facundobatista added 3 commits February 15, 2026 12:02

News entry.

7c16dc8

Merge branch 'main' into improve-globglob-docstrings

1aa3725

Added proper 'func' indication in News file.

917fc00

hugovk reviewed Feb 15, 2026

View reviewed changes

terryjreedy requested changes Feb 15, 2026

View reviewed changes

bedevere-app Bot added awaiting changes and removed awaiting core review labels Feb 15, 2026

terryjreedy added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels Feb 15, 2026

facundobatista added 2 commits February 18, 2026 11:17

Consistent use of backticks.

b2cb604

Merge branch 'main' into improve-globglob-docstrings

91abaa8

bedevere-app Bot added awaiting change review and removed awaiting changes labels Feb 18, 2026

bedevere-app Bot requested a review from terryjreedy February 18, 2026 14:20

facundobatista added 2 commits March 1, 2026 18:08

Improved wording.

edeca30

Merge branch 'main' into improve-globglob-docstrings

cf92fb7

gpshead reviewed Mar 2, 2026

View reviewed changes

Comment thread Lib/glob.py Outdated

consistent wording between the two docstrings

83ed8bf

gpshead approved these changes Mar 2, 2026

View reviewed changes

bedevere-app Bot added awaiting merge and removed awaiting change review labels Mar 2, 2026

facundobatista merged commit e542255 into python:main Mar 2, 2026
50 of 51 checks passed

bedevere-app Bot removed the awaiting merge label Mar 2, 2026

bedevere-app Bot removed the needs backport to 3.14 bugs and security fixes label Mar 2, 2026

bedevere-app Bot removed the needs backport to 3.13 bugs and security fixes label Mar 2, 2026

Uh oh!

Uh oh!

Conversation

facundobatista commented Feb 15, 2026 • edited by bedevere-app Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hugovk Feb 15, 2026

Choose a reason for hiding this comment

Uh oh!

gpshead Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

terryjreedy left a comment

Choose a reason for hiding this comment

Uh oh!

bedevere-app Bot commented Feb 15, 2026

Uh oh!

facundobatista commented Feb 18, 2026

Uh oh!

bedevere-app Bot commented Feb 18, 2026

Uh oh!

facundobatista commented Feb 18, 2026

Uh oh!

facundobatista commented Mar 1, 2026

Uh oh!

Uh oh!

facundobatista commented Mar 2, 2026

Uh oh!

Uh oh!

miss-islington-app Bot commented Mar 2, 2026

Uh oh!

bedevere-app Bot commented Mar 2, 2026

Uh oh!

bedevere-app Bot commented Mar 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

facundobatista commented Feb 15, 2026 •

edited by bedevere-app Bot

Loading